% Copyright 2011-2012 David Hadka.  All Rights Reserved.
%
% This file is part of the MOEA Framework User Manual.
%
% Permission is granted to copy, distribute and/or modify this document under
% the terms of the GNU Free Documentation License, Version 1.3 or any later
% version published by the Free Software Foundation; with the Invariant Section
% being the section entitled "Preface", no Front-Cover Texts, and no Back-Cover
% Texts.  A copy of the license is included in the section entitled "GNU Free
% Documentation License".

\chapter{Developer Guide}

This chapter outlines the coding practices to be used by contributors to the core MOEA Framework library.  In addition, many of the internal policies used by MOEA Framework administrators, managers and developers are outlined.

Much of the strategies used by the developers and managers are discussed in detail in the open book Producing Open Source Software by Karl Fogel.  This book can be viewed or downloaded from \webpage{http://producingoss.com/}.

\section{Version Numbers}
A \texttt{major.minor} version numbering scheme is used for all releases of the MOEA Framework.  Compatibility between two versions of the software can be determined by comparing the version numbers.

\begin{itemize}
  \item In general, downgrading to an older version should never be allowed.  The older version likely includes bugs or is missing features potentially used by the newer version.

  \item Compatibility is guaranteed when upgrading to a newer version that shares the same \texttt{major} version.

  \item Compatibility is NOT guaranteed when upgrading to a new version with a different \texttt{major} version number.  Deprecated API is removed when the \texttt{major} version is incremented, and programs relying on deprecated API will not function with the new version.
\end{itemize}

\section{Release Cycle}
The MOEA Framework is a research tool, and as such experiences rapid periods of development.  To provide these updates in a timely manner, new minor versions are released approximately on a five to six week cycle.  New releases are immediately available for download from \webpage{http://www.moeaframework.org} and are announced on \webpage{http://www.freecode.com}.

Prior to every release, the MOEA Framework must pass all testing code to ensure it functions as expected.  Furthermore, the code must pass a number of code quality and code style checks.

Major version increments will occur approximately every one to two years.  The decision to release a new major version will depend on the state of the codebase.  Major releases serve as a time for spring cleaning, allowing developers to remove old, deprecated API.

\section{API Deprecation}
Throughout the lifetime of a software project, certain API elements may be deemed unused, redundant or flawed by the developers and users.  A process is established to facilitate the identification, cleanup and removal of such API elements.  Once a consensus is reached that a certain API element is to be removed, it will be marked as \java{@Deprecated} in the next release.  This annotation serves as a reminder to all developers and users that the marked class, variable, constructor or method should be avoided in all client code.

Deprecated API elements can be identified in a number of ways.  First, the Java compiler will emit warning messages whenever deprecated API is referenced.  Second, most IDEs will highlight all uses of deprecated API with warning messages.  Lastly, the published Javadoc comments will clearly identify any deprecated method.  These Javadoc comments will typically also explain the reason for deprecation, specify the version when the API element will be removed, and provide the alternatives (if any) that should be used to replace the deprecated API.

In order to maintain backwards compatibility between minor releases, deprecated API elements will only be removed during the next major version release.  In addition, an API element must be deprecated for at least three months prior to removal.

\section{Code Style}

Clean and easy-to-understand code is of the utmost importance.  While no official code style standard is enforced, there are a number of guidelines contributors should follow to help produce clean code.

\begin{itemize}
  \item Every source code file should begin with a comment containing a copyright and license notice.
  
  \item Avoid using the asterisk to import all classes in a package.  Instead, add an import line for each class.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
import java.util.*;
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
import java.util.List;
import java.util.ArrayList;
      \end{lstlisting}
    \end{quote}
  
  \item Remove any import statements for classes not in use.
  
  \item Always add braces in loops or conditionals, even if the code block is only one line.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
for (int i=0; i<array.length; i++)
  array[i] = 0.0;
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
for (int i=0; i<array.length; i++) {
  array[i] = 0.0;
}
      \end{lstlisting}
    \end{quote}
  
  \item Never write an empty block of code.  At the minimum, include a comment indicating why the block is empty.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
try {
  Thread.sleep(1000);
} catch (InterruptedException e) {}
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
try {
  Thread.sleep(1000);
} catch (InterruptedException e) {
  //sleep was interrupted, continue processing
}
      \end{lstlisting}
    \end{quote}
  
  \item Add the \java{@Override} annotation to overriding methods.
  
  \item If you override the \java{equals(Object obj)} method, always override the \java{hashCode()} method as well.  For this project, the Apache Commons Lang library is used to build these methods.  For example:
    \begin{quote}
      \begin{lstlisting}[language=Java]
@Override
public int hashCode() {
  return new HashCodeBuilder()
      .append(algorithm)
      .append(problem)
      .toHashCode();
}

@Override
public boolean equals(Object obj) {
  if (obj == this) {
    return true;
  } else if ((obj == null) || (obj.getClass() != getClass())) {
    return false;
  } else {
    ResultKey rhs = (ResultKey)obj;
			
    return new EqualsBuilder()
        .append(algorithm, rhs.algorithm)
        .append(problem, rhs.problem)
        .isEquals();
  }
}
      \end{lstlisting}
    \end{quote}

  \item Avoid unnecessary whitespace unless the whitespace improves the clarity or readability of the code.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
List< String > grades = Arrays.asList( "A", "B", "C", "D", "F" );

for ( String grade : grades ) {
  ...
}
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
List<String> grades = Arrays.asList("A", "B", "C", "D", "F");

for (String grade : grades) {
  ...
}
      \end{lstlisting}
    \end{quote}
  
  \item Never compare strings with \java{==} or \java{!=}.  Use \java{equals} or \java{equalsIgnoreCase} instead.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
if ("yes" == inputTextField.getText()) {
  ...
}
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
if ("yes".equals(inputTextField.getText()) {
  ...
}
      \end{lstlisting}
    \end{quote}
  
  \item Avoid overriding \java{clone()} and \java{finalize()}.  If you must override these methods, always invoke \java{super.clone()} or \java{super.finalize()} in the method.

  \item Write only one statement per line.  Avoid multiple variable declarations on one line.  Also, initialize variables at their declaration whenever possible.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
double sum, product;
...
sum = 0.0;
product = 1.0;
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
double sum = 0.0;
double product = 1.0;
      \end{lstlisting}
    \end{quote}
  
  \item Fully document every variable, constructor and method.  The only place documentation is not necessary is on overridden methods if the inherited documentation is sufficient.

  \item Follow standard Java naming conventions.  Constants should be in \java{ALL_CAPS}, variables and methods in camelCase, etc.

  \item Class variables should never be publicly visible.  If the value is mutable, add the appropriate getter/setter methods.
    \begin{quote}
      Bad:
      \begin{lstlisting}[language=Java]
public int size;
      \end{lstlisting}
      
      Good:
      \begin{lstlisting}[language=Java]
private int size;

public int getSize() {
  return size;
}

public void setSize(int size) {
  this.size = size;
}
      \end{lstlisting}
    \end{quote}
\end{itemize}

\section{Licensing}
The MOEA Framework is licensed under the GNU Lesser General Public License, version 3 or later.  In order to ensure contributions can be legally released as part of the MOEA Framework, all contributions must be licensed under the GNU Lesser General Public License, version 3.

Modifications which are not licensed under the GNU Lesser General Public License, version 3, can still be bundled with the MOEA Framework library or distributed as a third-party extension.  In fact, the GNU Lesser General Public License specifically grants users of the MOEA Framework the right to bundle the library with an application released under any license of their choosing.

\section{Web Presence}
The following webpages are officially managed by the MOEA Framework development team.

\begin{description}
  \item[\webpage{http://www.moeaframework.org}] - The main website for the MOEA Framework, providing the latest downloads and documentation.
  \item[\webpage{http://sourceforge.net/projects/moeaframework}] - The web host for the MOEA Framework, also providing bug tracking and other support tools.
  \item[\webpage{http://www.freecode.com/projects/moea-framework}] - Announces new releases and other news to the open source community.
  \item[\webpage{http://www.openhatch.org/+projects/MOEA\%20Framework}] - Provides information for individuals wishing to contribute to the MOEA Framework.
\end{description}